GtkTreeSelection
<!-- ##### SECTION Short_Description ##### -->
-
+The selection object for #GtkTreeView
<!-- ##### SECTION Long_Description ##### -->
<para>
+The #GtkTreeSelection object is a helper object to manage the selection
+for a #GtkTreeView widget. The #GtkTreeSelection object is
+automatically created when a new #GtkTreeView widget is created, and
+cannot exist independentally of this widget. The primary reason the
+#GtkTreeSelection objects exists is for cleanliness of code and API.
+That is, there is no conceptual reason all these functions could not be
+methods on the #GtkTreeView widget instead of a separate function.
+</para>
+<para>
+The #GtkTreeSelection object is gotten from a #GtkTreeView by calling
+gtk_tree_view_get_selection(). It can be manipulated to check the
+selection status of the tree, as well as select and deselect individual
+rows. Selection is done completely view side. As a result, multiple
+views of the same model can have completely different selections.
+Additionally, you cannot change the selection of a row on the model that
+is not currently displayed by the view without expanding its parents
+first.
</para>
-<!-- ##### SECTION See_Also ##### -->
<para>
+One of the important things to remember when monitoring the selection of
+a view is that the "changed" signal is mostly a hint. That is, it may
+only emit one signal when a range of rows is selected. Additionally, it
+may on occasion emit a "changed" signal when nothing has happened
+(mostly as a result of programmers calling select_row on an already
+selected row).
+</para>
+<!-- ##### SECTION See_Also ##### -->
+<para>
+#GtkTreeView, #GtkTreeViewColumn, #GtkTreeDnd, #GtkTreeMode, #GtkTreeSortable, #GtkTreeModelSort, #GtkListStore, #GtkTreeStore, #GtkCellRenderer, #GtkCellEditable, #GtkCellRendererPixbuf, #GtkCellRendererText, #GtkCellRendererToggle
</para>
<!-- ##### STRUCT GtkTreeSelection ##### -->
<!-- ##### USER_FUNCTION GtkTreeSelectionFunc ##### -->
<para>
-
+A function used by gtk_tree_selection_set_select_function() to filter
+whether or not a row may be selected. It is called whenever a row's
+state might change. A return value of %TRUE indicates to @selection
+that it is okay to change the selection.
</para>
-@selection:
-@model:
-@path:
-@path_currently_selected:
-@data:
-@Returns:
+@selection: A #GtkTreeSelection
+@model: A #GtkTreeModel being viewed
+@path: The #GtkTreePath of the row in question
+@path_currently_selected: %TRUE, if the path is currently selected
+@data: user data
+@Returns: %TRUE, if the selection state of the row can be toggled
<!-- ##### USER_FUNCTION GtkTreeSelectionForeachFunc ##### -->
<para>
-
+A function used by gtk_tree_selection_selected_foreach() to map all
+selected rows. It will be called on every selected row in the view.
</para>
-@model:
-@path:
-@iter:
-@data:
+@model: The #GtkTreeModel being viewed
+@path: The #GtkTreePath of a selected row
+@iter: A #GtkTreeIter pointing to a selected row
+@data: user data
<!-- ##### FUNCTION gtk_tree_selection_set_mode ##### -->
<!-- ##### SIGNAL GtkTreeSelection::changed ##### -->
<para>
-
+Emitted whenever the selection has (possibly) changed. Please note that
+this signal is
</para>
@treeselection: the object which received the signal.
information can be found on this in the <link
linkend="GtkTreeStore">GtkTreeModel</link> section.
<informalexample><programlisting><![CDATA[
+enum
+{
+ COLUMN_ONE,
+ N_COLUMNS
+};
+
{
GtkTreeStore *model;
GtkWidget *view;
/* Create a model. We are using the store model for now, though we
* could use any other GtkTreeModel */
- model = gtk_tree_store_new_with_values (1, G_TYPE_STRING);
+ model = gtk_tree_store_new_with_values (N_COLUMNS, G_TYPE_STRING);
+
+ /* custom function to fill the model with data */
populate_tree_model (model);
/* Create a view */
* reference */
g_object_unref (G_OBJECT (model));
- /* Create a cell render and arbitrarily make it red for demonstartion
- *purposes */
+ /* Create a cell render and arbitrarily make it red for demonstration
+ * purposes */
cell_renderer = gtk_cell_renderer_text_new ();
g_object_set (G_OBJECT (cell_renderer), "foreground", "red", NULL);
* cell_renderer to the first column of the model */
column = gtk_tree_view_column_new_with_attributes ("title",
cell_renderer,
- "text", 0,
+ "text", COLUMN_ONE,
NULL);
/* Add the column to the view. */
gtk_tree_view_append_column (GTK_TREE_VIEW (view), column);
+
+ /* Now we can manipulate the view just like any other GTK widget */
+ ...
}
]]>
</programlisting></informalexample>
projects / gtk4.git / commitdiff